---
title: 使用集成
i18nReady: true
---

import IntegrationsNav from '~/components/IntegrationsNav.astro';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'

import { Steps } from '@astrojs/starlight/components'

使用 **Astro 集成**只需几行代码就能为你的项目添加新的功能和行为。你可以自己编写一个自定义的集成，可以使用官方集成，还可以使用社区内的集成。

集成能够...

- 解锁 React、Vue、Svelte、Solid 和其他流行的 UI 框架。
- 只需几行代码就能整合 Tailwind 和 Partytown 等工具。
- 为你的项目添加新功能，如自动生成网站地图。
- 编写自定义代码，与构建过程、开发服务器等挂钩。

:::tip[集成目录]
在我们的 [集成目录](https://astro.build/integrations/) 中浏览或搜索数百个官方和社区集成的完整集成。在这里你找到可以添加到你的 Astro 项目中的包，涵盖了身份验证、分析、性能、SEO、无障碍、UI、开发者工具等场景。
:::

## 官方集成

以下集成由 Astro 维护。

<IntegrationsNav />

## 自动集成设置

Astro 包含了一个 `astro add` 命令来自动设置官方集成。许多社区插件也可以使用这个命令添加。请查阅每个集成的文档，以确定是否支持 `astro add`，或者你是否需要[手动安装](#手动安装)。

只需用你的包管理器运行 `astro add` 命令，我们的自动集成向导将更新你的配置文件并安装任何必要的依赖。

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npx astro add react
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm astro add react
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn astro add react
  ```
  </Fragment>
</PackageManagerTabs>

甚至还可以同时配置多个集成！

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npx astro add react tailwind partytown
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm astro add react tailwind partytown
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn astro add react tailwind partytown
  ```
  </Fragment>
</PackageManagerTabs>

:::note[处理集成依赖]
如果你在添加集成后看到 `"Cannot find package '[package-name]'` 或其他类似警告，这意味着你的包管理器可能没有安装[对等依赖](https://nodejs.org/en/blog/npm/peer-dependencies/)。要安装这些缺失的包，请运行 `npm install [package-name]`。
:::

## 手动安装

Astro 集成总是添加在 `astro.config.mjs` 文件中的 `integrations` 属性。

有三种常见的方法来导入集成到你的 Astro 项目：
1. [安装 npm 包集成](#安装-npm-包)。
2. 从项目内部的本地文件导入你自己的集成。
3. 直接在配置文件中内联编写集成。

    ```js
    // astro.config.mjs
    import { defineConfig } from 'astro/config';
    import installedIntegration from '@astrojs/vue';
    import localIntegration from './my-integration.js';

    export default defineConfig({
      integrations: [
        // 1. 从已安装的 npm 包中导入
        installedIntegration(),
        // 2. 从本地 JS 文件导入
        localIntegration(),
        // 3. 内联对象
        {name: 'namespace:id', hooks: { /* ... */ }},
      ]
    });
    ```

查看[集成 API](/zh-cn/reference/integrations-reference/) 参考资料，了解所有不同的集成编写方式。

#### 安装 NPM 包

使用包管理器安装 NPM 包集成，然后手动更新 `astro.config.mjs`。

例如，安装 `@astrojs/sitemap` 集成：

<Steps>
1. 使用你偏好的包管理器将集成安装到项目依赖中：

   <PackageManagerTabs>
     <Fragment slot="npm">
     ```shell
     npm install @astrojs/sitemap
     ```
     </Fragment>
     <Fragment slot="pnpm">
     ```shell
     pnpm add @astrojs/sitemap
     ```
     </Fragment>
     <Fragment slot="yarn">
     ```shell
     yarn add @astrojs/sitemap
     ```
     </Fragment>
   </PackageManagerTabs>

2. 将集成导入到你的 `astro.config.mjs` 文件，并将其连同任何配置选项添加到你的 `integrations[]` 数组中：

    ```js title="astro.config.mjs" ins={2} ins="sitemap()"
    import { defineConfig } from 'astro/config';
    import sitemap from '@astrojs/sitemap';

    export default defineConfig({
      // ...
      integrations: [sitemap()],
      // ...
    });
    ```

    请注意，不同的集成可能有不同的配置设置。阅读每个集成的文档，并将任何必要的配置选项应用到 `astro.config.mjs` 中你所选择的集成上。
</Steps>

### 自定义选项

集成几乎都是以工厂函数的形式编写的，并返回真实的集成对象。这使得你可以通过向工厂函数传递参数和选项定制集成。

```js
integrations: [
  // 示例：用函数参数来定制你的集成
  sitemap({filter: true})
]
```

### 切换集成

你可以切换集成启用状态，而不用担心遗留的 `undefined` 和布尔值问题，Astro 会自动忽略假值的集成。

```js
integrations: [
  // 示例：在 Windows 上跳过网站地图的构建
  process.platform !== 'win32' && sitemap()
]
```

## 更新集成

要同时更新所有官方集成，运行 `@astrojs/upgrade` 命令。它会把 Astro 和所有官方集成更新到最新版本。

### 自动更新

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # 同时升级 Astro 和官方集成到最新版本
  npx @astrojs/upgrade
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # 同时升级 Astro 和官方集成到最新版本
  pnpm dlx @astrojs/upgrade
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # 同时升级 Astro 和官方集成到最新版本
  yarn dlx @astrojs/upgrade
  ```
  </Fragment>
</PackageManagerTabs>

### 手动更新

要手动更新一个或多个集成，使用你的包管理器对应的命令。

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # 示例：升级 React 和 Tailwind 集成
  npm install @astrojs/react@latest @astrojs/tailwind@latest
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # 示例：升级 React 和 Tailwind 集成
  pnpm add @astrojs/react@latest @astrojs/tailwind@latest
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # 示例：升级 React 和 Tailwind 集成
  yarn add @astrojs/react@latest @astrojs/tailwind@latest
  ```
  </Fragment>
</PackageManagerTabs>

## 移除集成

要移除某个集成，首先从你的项目中卸载它

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm uninstall @astrojs/react
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm remove @astrojs/react
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn remove @astrojs/react
  ```
  </Fragment>
</PackageManagerTabs>

接下来，从 `astro.config.*` 文件中移除该集成：

```js title="astro.config.mjs" del={3,7}
import { defineConfig } from 'astro/config';

import react from '@astrojs/react';

export default defineConfig({
  integrations: [
    react()
  ]
});
```

## 寻找更多集成

你可以在 [Astro 集成目录](https://astro.build/integrations/)中找到许多由社区开发的集成。点击链接查看详细的使用和配置说明。

## 构建自己的集成

Astro 的集成 API 受到 Rollup 和 Vite 的启发，其设计使任何曾经写过 Rollup 或 Vite 插件的人都感到熟悉。

查看[集成 API](/zh-cn/reference/integrations-reference/)，了解集成的作用以及如何自己编写一个集成。
